home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 21 / AACD 21.iso / AACD / Resources / Online / Miami / MiamiSDK / README < prev   
Text File  |  1997-12-30  |  16KB  |  427 lines
  1. $VER: MiamiSDK 2.11  (30.12.97)
  2.  
  3. © Copyright 1997 Nordic Global Inc. (kruse@nordicglobal.com)
  4. All rights reserved.
  5.  
  6. Please see the enclosed files COPYRIGHT and DISTRIBUTION for
  7. more information on copyright and distribution status.
  8.  
  9.  
  10.  
  11. Miami Software Development Kit
  12. ------------------------------
  13.  
  14. This archive contains all files required to develop application
  15. software for Miami (and other compatible TCP/IP protocol stacks)
  16. with SAS/C, for use with AmigaOS.
  17.  
  18. If you have previously used other development kits (e.g. the kit
  19. for AmiTCP/IP) then please read this file carefully. There are some
  20. differences that you need to be aware of.
  21.  
  22.  
  23.  
  24. Installation
  25. ------------
  26.  
  27. No specific installation is required. Just unarchive the files
  28. anywhere you like. HOWEVER...
  29.  
  30.  ...DO NOT copy the C header files over your existing files (in
  31.  the "include:" directory).
  32.  
  33.  ...DO NOT copy the libraries over your existing libraries (in
  34.  the "lib:" directory).
  35.  
  36.  ...DO NOT copy any of the files in this archive "over" your
  37.  existing AmiTCP/IP developer kit (if you have one installed).
  38.  Instead start over in a separate directory. DO NOT mix files from
  39.  this developer kit with files from other developer kits.
  40.  
  41.  
  42. Also, many makefiles require you to create one or more of the
  43. assigns
  44.  
  45.  "assign netinclude: netinclude"
  46.  
  47.  "assign netlib: netlib"
  48.  
  49.  
  50. These assigns are recommended, and the remainder of this document
  51. assumes that these assigns exist.
  52.  
  53.  
  54.  
  55. Usage notes
  56. -----------
  57.  
  58. - At the moment only SAS/C is officially supported. You might be
  59.   able to use other C compilers as well, if you make the necessary
  60.   adaptations yourself. See the section "C compiler notes"
  61.   below.
  62.  
  63. - In addition to ordinary 680x0 binaries this developer kit can
  64.   also be used to create PPC ELF binaries for the Phase-5
  65.   PowerUP kernel, which directly use network calls. You need
  66.   the PPC version of SAS/C for this. At the moment the inline
  67.   functions of the developer kit transparently transfer all
  68.   network calls to the 680x0 side, but this behavior may change
  69.   in the future if/when more parts of the protocol stack are
  70.   implemented in native PPC code. 
  71.  
  72. - Your compiler must use 32-bit integers (default for SAS/C).
  73.   16-bit integers or 64-bit integers are not supported. The
  74.   MiamiSDK uses "long" in many places where other header files
  75.   use "int". This change is intended to make 16-bit-integer or
  76.   64-bit-integer support possible in a future version (by making
  77.   function call parameters and C structures independent of your
  78.   C compiler's integer settings), probably in combination with
  79.   yet another, but compatible, type change (for Posix.1g).
  80.  
  81.   The current drawback of this change from "int" to "long" is
  82.   that you may occasionally get warnings 88 ("argument type
  83.   incorrect") regarding "int *" vs "long *", in particular
  84.   for functions like getsockopt(). Either ignore the warnings
  85.   or change the corresponding objects in your code from "int"
  86.   to "long" (which is what they should have been declared as
  87.   in the first place, really...)
  88.  
  89. - This developer kit supports the following APIs:
  90.  
  91.   - bsdsocket.library (AmiTCP/IP-compatible, with some
  92.     extensions for multicasting, T/TCP, IPv6, new socket options
  93.     etc.).
  94.  
  95.   - usergroup.library (AmiTCP/IP-compatible)
  96.  
  97.   - miami.library: functions specifically for Miami (name
  98.     starting with Miami...()).
  99.     
  100.   - miami.library: general network functions which are part
  101.     of the Posix.1g DNI/Socket standard, but not part of the
  102.     bsdsocket API (e.g. inet_pton/ntop(), getaddrinfo() etc.).
  103.  
  104.   - miamibpf.library: BPF (Berkely Packet Filter) for use with
  105.     Miami.
  106.  
  107.   - miamipcap.library: libpcap, a packet capture library for
  108.     use with Miami and miamibpf.library.
  109.     
  110.   The developer kit is IPv6-ready, even though IPv6 is not
  111.   currently supported by any AmigaOS protocol stack. This means
  112.   if you use MiamiSDK now to develop your programs, and follow
  113.   all guidelines regarding protocol independence, then your
  114.   programs will automatically be IPv6-compatible once IPv6-
  115.   supporting TCP/IP stacks appear for AmigaOS.
  116.  
  117. - Programs built with the Miami Software Development Kit are
  118.   NOT restricted to Miami. They will also work with other
  119.   protocol stacks such as AmiTCP/IP, TermiteTCP etc., in the
  120.   same way as if you had built the programs with the AmiTCP/IP
  121.   native developer kit.
  122.  
  123.   Obviously, if your program requires Miami-specific
  124.   features such as Multicasting, T/TCP or functions in
  125.   miami.library or any other library only provided by Miami
  126.   then it will only work with Miami, not with other stacks,
  127.   unless other stacks provide Miami emulation libraries in
  128.   the future.
  129.  
  130. - The Miami Software Development Kit contains support for
  131.   several features available only in Miami, and not accessible
  132.   through the AmiTCP/IP native developer kit (such as Multicasting
  133.   and T/TCP). If you use this Miami Software Development Kit
  134.   then you do NOT need older Miami development archives (in
  135.   particular the file "ttcp.h") any more, which were intended
  136.   as add-ons for the AmiTCP/IP NDK.
  137.  
  138. - The Miami Software Development Kit is based on 4.4BSD, not
  139.   on earlier BSD versions like other development kits. For the
  140.   majority of programs this should NOT cause any compatibility
  141.   problems. However some names of C header files have changed,
  142.   as well as the location where individual symbols are defined,
  143.   usually in the same way things have changed in BSD from
  144.   version 4.3 to 4.4.
  145.  
  146. - The Miami Software Development Kit ONLY contains actual
  147.   networking functions, NOT most of the non-networking Unix
  148.   functions found in other kits (e.g. ixemul/ixnet).
  149.  
  150.   If your sources currently need any of these functions then
  151.   you should rewrite the sources to use equivalent AmigaOS
  152.   functions instead. Alternatively you could get the required
  153.   functions from other sources.
  154.  
  155. - You might notice that, unlike Unix header files, in this kit
  156.   each header file automatically includes all other header files
  157.   it requires, just like AmigaOS header files. This should greatly
  158.   simplify things for you, and often means that you do NOT have
  159.   to include OS-specific files (like <exec/types.h>) or very
  160.   generic files (like <sys/types.h>) manually any more.
  161.  
  162. - Some of the data structures in header files were not naturally
  163.   aligned, and have been replaced with new versions which are
  164.   naturally aligned, and are thus compatible with PPC kernels.
  165.   Old versions were renamed by adding a "_u" suffix to the
  166.   original names. The following structures and corresponding
  167.   access functions were affected by this change, and require
  168.   changes in applications:
  169.  
  170.   - libraries/usergroup.h:
  171.     new, aligned:    struct UserGroupCredentials,
  172.                      miami.library/MiamiGetCredentials()
  173.     old, unaligned:  struct UserGroupCredentials_u,
  174.                      usergroup.library/getcredentials()
  175.  
  176.   If you intend to use your program with PPC kernels or a PPC
  177.   API translator then you MUST use the new versions of those
  178.   structures and the new access functions. However these new
  179.   versions are not compatible with older protocol stacks. This
  180.   means if you want your program to work with older protocol
  181.   stacks then use the old versions. If you want both (PPC
  182.   compatibility AND compatibility with older protocol stacks)
  183.   then use the old versions in 68k code, and the new versions
  184.   in PPC code (via conditional compilation).
  185.  
  186.   Also the following structures were changed for correct
  187.   alignment, but without providing new access functions or
  188.   backward-compatibility. This should not be a problem
  189.   for application programmers, because those structures are
  190.   only used by routing sockets, and except for tools that
  191.   shipped with Miami no old software should be using routing
  192.   sockets anyway. If you want to use routing sockets in your
  193.   software then you need to require miami.library >= V12.
  194.  
  195.   - net/route.h: struct rt_msghdr
  196.   - net/if.h: struct if_msghdr, struct ifa_msghdr
  197.   
  198. - Normally libraries are opened automatically for you. All
  199.   you need to do is include the right "proto" header file in
  200.   your source files, e.g. <proto/miami.h> for "miami.library".
  201.   In this case DO NOT define "struct Library *MiamiBase;"
  202.   in your code.
  203.  
  204. - If libraries are opened automatically for you then the
  205.   default minimum library versions are as follows:
  206.  
  207.   bsdsocket.library V4
  208.   miami.library V12
  209.   miamibpf.library V1
  210.   miamipcap.library V3
  211.   usergroup.library V4
  212.  
  213.   This means AmiTCP/IP 4.x or higher or Miami 1.x or higher is
  214.   required. If you access any functions in miami.library then
  215.   Miami 3.0 or higher is required.
  216.  
  217.   If you want to support older versions of those protocol
  218.   stacks then you can manually override the minimum library
  219.   versions in the following global variables. Examples:
  220.  
  221.   unsigned long _MiamiVersion=12;
  222.   unsigned long _MiamiBPFVersion=1;
  223.   unsigned long _MiamiPCapVersion=3;
  224.   unsigned long _SocketVersion=4;
  225.   unsigned long _UserGroupVersion=4;
  226.  
  227. - If libraries are opened automatically for you then the global
  228.   variables "errno" and "herrno" are automatically linked to the
  229.   corresponding variables in the TCP/IP kernel (socket.library
  230.   and usergroup.library), i.e. after calling functions in these
  231.   libraries those variables in your program reflect the current
  232.   error status.
  233.   
  234.   However this mechanism only works with 680x0 binaries, NOT
  235.   with PPC binaries, because with the current PPC kernel
  236.   sharing variables would cause a major decrease in
  237.   performance. To check error conditions from PPC binaries you
  238.   need to use the functions Errno() and ug_GetErr(). DO NOT
  239.   try to set up variable sharing manually (via UGT_ERRNOPTR
  240.   or SBTC_ERRNOPTR), because that mechanism does not work
  241.   reliably with PPC binaries because of CPU cache
  242.   inconsistencies.
  243.  
  244. - If you do NOT want to use the "auto-open libraries"
  245.   feature, but want to open the libraries yourself, then
  246.   define the corresponding library bases in your program
  247.   and open/close the libraries manually, e.g.
  248.  
  249.   struct Library *MiamiBase=0;
  250.  
  251.   /* ... */
  252.   
  253.   MiamiBase=OpenLibrary(MIAMINAME,12);
  254.  
  255.   /* ... */
  256.  
  257.   CloseLibrary(MiamiBase);  
  258.  
  259.   Note that in this case you might have to do some additional
  260.   setup, which the auto-open code usually does for you
  261.   (SocketBaseTags(), ug_SetupContextTags()), in particular if
  262.   you want "errno" to automatically reflect the error code of
  263.   socket calls. Please see Socket.doc and UserGroup.doc for
  264.   more information on this.
  265.  
  266. - If you are using the small data model with 680x0 binaries
  267.   then add the compiler options
  268.   "INCDIR=netinclude: LIB netlib:miami.lib". For the large data
  269.   model with 680x0 binaries add
  270.   "INCDIR=netinclude: LIB netlib:miaminb.lib". For PPC binaries
  271.   use the compiler option "INCDIR=netinclude:" and add the
  272.   library "netlib:miamippc.a" to your linker call after all
  273.   program binaries, and before "lib:scppc.a".
  274.  
  275. - Example:
  276.  
  277.   /* for 680x0: sc INCDIR=netinclude: LIB netlib:miami.lib LINK test.c */
  278.   /* for PPC: scppc INCDIR=netinclude: OBJNAME=test.oppc test.c
  279.               ppc-amigaos-ld -r -o test.elf lib:c_ppc.o
  280.                test.oppc netlib:miamippc.a lib:scppc.a lib:end.o */
  281.  
  282.   #include <proto/socket.h>
  283.   #include <sys/socket.h>
  284.  
  285.   void main(void) {
  286.     int s;
  287.     s=socket(AF_INET,SOCK_STREAM,0);
  288.     /* some more code */
  289.     CloseSocket(s);
  290.   }
  291.  
  292. - NOTE: Library bases MAY NOT be shared among processes, i.e. if
  293.   more than one process in your program accesses network
  294.   libraries then you MAY NOT use global library bases (and
  295.   auto-opening of libraries). Instead use local library bases and
  296.   open the libraries manually, e.g.
  297.  
  298.   void func(void) {
  299.     int s;
  300.     struct Library *SocketBase;
  301.     if(SocketBase=OpenLibrary(SOCKETNAME,4)) {
  302.       s=socket(AF_INET,SOCK_STREAM,0);
  303.       /* some more code */
  304.       CloseSocket(s);
  305.       CloseLibrary(SocketBase);
  306.     }
  307.   }
  308.  
  309. - It is possible to make use of Miami's additional functions
  310.   (in particular the IPv6 compatibility) without sacrificing
  311.   compatibility with older protocol stacks, if you use runtime
  312.   checks, e.g. like this:
  313.   
  314.   Define "MiamiBase" yourself, so the auto-open code does not
  315.   try to open the library (and then complain if it cannot find
  316.   it):
  317.   
  318.     struct Library *MiamiBase=0;
  319.     
  320.   Try to open miami.library yourself, but don't quit if it does
  321.   not work:
  322.   
  323.     MiamiBase=OpenLibrary("miami.library",0);
  324.     
  325.   Use old-style socket access for older stacks, and new style
  326.   (protocol-independent) access for Miami >= 3.0:
  327.  
  328.     if(MiamiBase&&(MiamiBase->lib_Version>=12)) {
  329.       /* use getaddrinfo() here to resolve the server name,
  330.          then call socket() with the returned family (IPv4
  331.          or IPv6) */
  332.     } else {
  333.       /* use gethostbyname() here to resolve the server name,
  334.          then call socket() with AF_INET (IPv4 only) */
  335.     }
  336.  
  337.   At the end of your program close MiamiBase manually:
  338.   
  339.     if(MiamiBase) {
  340.         CloseLibrary(MiamiBase);
  341.         MiamiBase=0;
  342.     }
  343.     
  344.   Similar methods can be used to support T/TCP in Miami. See
  345.   the file "examples/ttcptest.c" for more details on this.
  346.   
  347.   Also read the note above regarding alignment problems in
  348.   data structures and effects on PPC compatibility.
  349.  
  350. - This developer kit does not contain the header files necessary
  351.   to access MiamiSSL. If you would like to add SSL support to your
  352.   program then please contact "kruse@nordicglobal.com" to get the
  353.   MiamiSSL developer kit.
  354.  
  355. - The AmiTCP/IP developer kit has some header files in the
  356.   directory "amitcp". Corresponding files for the Miami SDK are
  357.   in the directory "bsdsocket", i.e. you need to e.g. include
  358.   <bsdsocket/socketbasetags.h> instead of <amitcp/socketbasetags.h>.
  359.  
  360. - If you are new to TCP/IP programming then please have a look at
  361.   the file "help/TCPIP.guide". It contains explanations about
  362.   differences between Unix network programming and Amiga network
  363.   programming, and can be used as a tutorial on TCP/IP, in
  364.   combination with the text book mentioned in that file
  365.   
  366.  
  367.  
  368. C compiler notes
  369. ----------------
  370.  
  371. Currently only SAS/C is officially supported. The header files
  372. should be sufficiently portable to work with other compilers
  373. as well, except possibly for the way "time.h" is included by
  374. "sys/time.h". (This weirdness is caused by some compatibility
  375. problems between structures in AmigaOS and BSD.)
  376.  
  377. However there are a few other possible compatibility issues:
  378.  
  379.  
  380. - The following rules need to be observed if you want to compile
  381.   680x0 and PPC binaries with SAS/C from the same sources:
  382.  
  383.   - Varargs versions of library calls currently cannot be used.
  384.     This means you need to use vsyslog() instead of syslog(),
  385.     SocketBaseTagList() instead of SocketBaseTags() etc.
  386.     
  387.   - Don't assume that errno and herrno are set automatically
  388.     for you. Get the error status manually, by calling
  389.     Errno(), ug_GetErr() etc.
  390.  
  391.   - Don't use struct UserGroupCredentials_u, or any
  392.     functions that accept or return that structure.
  393.  
  394. - For 680x0 binaries most functions are accessed through
  395.   #pragma calls only, i.e. no function stubs exist, except
  396.   for those functions which cannot be called directly through
  397.   a #pragma call (see below). If your compiler does not support
  398.   SAS/C-compatible #pragma calls then you need to modify the
  399.   #pragma calls or create your own function stubs from the
  400.   #pragma calls or from the enclosed fd-files. For PPC binaries
  401.   inline functions are used to call the PowerUp kernel and
  402.   transfer control to the 680x0 side.
  403.  
  404. - Functions which pass or return structures as parameters cannot
  405.   be used in conjunction with 680x0 #pragma calls, so function
  406.   stubs are provided for them in miami.lib and miaminb.lib. The
  407.   critical functions which require function stubs are:
  408.  
  409.   - inet_lnaof
  410.   - inet_makeaddr
  411.   - inet_netof
  412.   - inet_ntoa
  413.   - select (which really maps to WaitSelect())
  414.  
  415.   Note that the way a C compiler passes or returns structures
  416.   is NOT standardized. Your compiler may very well do this in
  417.   a different way than SAS/C does, so the function stubs in
  418.   miami.lib and miaminb.lib might not work with your compiler.
  419.  
  420. - The library-auto-open feature is specific to SAS/C (using
  421.   _STI... and _STD... functions). It ONLY works if you use the
  422.   standard SAS/C startup code, and probably will not work
  423.   with other compilers at all. It works both with 680x0
  424.   binaries and with PPC binaries.
  425.  
  426. *EOF*
  427.